Sending Messages with the Client Bus

In order to send a message from a client you need to create a Message and send it through an instance of MessageBus. In this simple example we send it to the subject 'HelloWorldService'.

public class HelloWorld implements EntryPoint {

  // Get an instance of the RequestDispatcher
  private RequestDispatcher dispatcher = ErraiBus.getDispatcher();

  public void onModuleLoad() {
    Button button = new Button("Send message");

    button.addClickHandler(new ClickHandler() {
      public void onClick(ClickEvent event) {
        // Send a message to the 'HelloWorldService'.
        MessageBuilder.createMessage()
          .toSubject("HelloWorldService") // (1)
          .signalling() // (2)
          .noErrorHandling() // (3)
          .sendNowWith(dispatcher); // (4)
        });

        [...]
      }
   }
}

In the above example we build and send a message every time the button is clicked. Here's an explanation of what's going on as annotated above:

1. We specify the subject we wish to send a message to. In this case, "HelloWorldService".

2. We indicate that we wish to only signal the service, meaning, that we're not sending a qualifying command to the service. For information on this, read the section on Protocols.

3. We indicate that we do not want to provide an ErrorCallback to deal with errors for this message.

4. We transmit the message by providing an instance to the RequestDispatcher

Receiving Messages on the Server Bus / Server Services

Every message has a sender and at least one receiver. A receiver is as it sounds--it receives the message and does something with it. Implementing a receiver (also referred to as a service) is as simple as implementing our standard MessageCallback interface, which is used pervasively across, both client and server code. Let's begin with server side component that receives messages:

@Service
  public class HelloWorldService implements MessageCallback {
    public void callback(Message message) {
      System.out.println("Hello, World!");
    }
  }

He we declare an extremely simple service. The @Service annotation provides a convenient, meta-data based way of having the bus auto-discover and deploy the service.

Sending Messages with the Server Bus

In the following example we extend our server side component to reply with a message when the callback method is invoked. It will create a message and address it to the subject 'HelloWorldClient':

@Service
public class HelloWorldService implements MessageCallback {

  private RequestDispatcher dispatcher;

  @Inject
  public HelloWorldService(RequestDispatcher dispatcher) {
    dispatcher = dispatcher;
  }

  public void callback(CommandMessage message) {
    // Send a message to the 'HelloWorldClient'.
    MessageBuilder.createMessage()
      .toSubject("HelloWorldClient") // (1)
      .signalling()                  // (2)
      .with("text", "Hi There")      // (3)
      .noErrorHandling()             // (4)
      .sendNowWith(dispatcher);      // (5)
    });
  }
}

The above example shows a service which sends a message in response to receiving a message. Here's what's going on:

1. We specify the subject we wish to send a message to. In this case, "HelloWorldClient". We are sending this message to all clients which are listening in on this subject. For information on how to communicate with a single client, see Section 2.6.

2. We indicate that we wish to only signal the service, meaning that we're not sending a qualifying command to the service. For information on this, read the section on Protocols.

3. We add a message part called "text" which contains the value "Hi there".

4. We indicate that we do not want to provide an ErrorCallback to deal with errors for this message.

5. We transmit the message by providing an instance of the RequestDispatcher.

Receiving Messages on the Client Bus/ Client Services

Messages can be received asynchronously and arbitriraily by declaring callback services within the client bus. As ErraiBus maintains an open COMET channel at all times, these messages are delivered in real time to the client as they are sent. This provides built-in push messaging for all client services.

public class HelloWorld implements EntryPoint {

  private MessageBus bus = ErraiBus.get();

  public void onModuleLoad() {
     [...]

     /*
      * Declare a service to receive messages on the subject
      * "BroadcastReceiver".
      */
     bus.subscribe("BroadcastReceiver", new MessageCallback() {
       public void callback(CommandMessage message) {
         /*
          * When a message arrives, extract the "text" field and
          * do something with it
          */
          String messageText = message.get(String.class, "text");
        }
     });

     [...]
  }
}

In the above example, we declare a new client service called "BroadcastReceiver" which can now accept both local messages and remote messages from the server bus. The service will be available in the client to receive messages as long the client bus is and the service is not explicitly de-registered.

Local Services

On the client or the server, you can create a local receiver which only receives messages that originated on the local bus. A local server-side service only receives messages that originate on that server, and a local client-side service only receives messages that originated on that client.

To create a local receiver using the declarative API, use the @Local annotation in conjunction with @Service:

@Local
@Service
  public class HelloIntrovertService implements MessageCallback {
    public void callback(Message message) {
      System.out.println("Hello, me!");
    }
  }

To create a local receiver using through programmatic service registration, use the subscribeLocal() method in place of subscribe():

public void registerLocalService(MessageBus bus) {
  bus.subscribeLocal("LocalBroadcastReceiver", new MessageCallback() {
    public void callback(Message message) {
       String messageText = message.get(String.class, "text");
     }
  });
}

Both examples above work in client- and server-side code.